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I.  INTRODUCTION 

This  report  provides  a  user's  manual  for  several  utility  programs, 
which  have  been  used  as  aids  during  the  development  of  the  STAR  combat  sim¬ 
ulation  model. 

Section  II  describes  a  program  for  rapidly  producing  contour  maps  of 
the  STAR  battlefield  area  and  overlaying  information  of  various  types  on  the 
maps. 

Section  III  describes  a  program  for  reconciling  two  computer  programs 
which  are  mostly  identical,  but  contain  some  differences.  Such  programs 
have  frequently  resulted  during  the  STAR  development  as  several  groups  simul¬ 
taneously  build  new  modules  for  incorporation  into  the  base  program. 

Section  IV  describes  a  program  for  productna  Tech  report  or  thesis  - 
ready  copies  of  computer  code  without  requiring  photo-reduction. 
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II.  BATTLEFIELD  MAP  PLOT  PROGRAMS 

As  an  aid  to  visualizing  the  progress  of  a  simulated  battle,  and 
especially  as  an  aid  in  the  scenario  formulation  process,  a  program  has  been 
written  to  rapidly  prepare  contour  maps  of  the  STAR  battlefield  area  with 
a  series  of  optional  overlays.  The  program  is  written  in  FORTRAN  and  uses 
standard  VERSATEC  plotter  routines . ^re^‘  ^  Several  data  sets  defining  the 
maps  are  stored  on  disk  by  preprocessor  programs  and  read  back  by  the  plot 
program.  This  saves  substantial  time  since  the  preprocessing  is  quite  lengthy 
for  preparing  the  contour  map.  Section  A  of  this  chapter  will  describe  the 
plot  program  options.  Section  B  briefly  discusses  the  preprocessor  programs. 
A.  Plot  Options 

A  program  listing  for  the  map  plot  program  is  given  in  Figure  1. 
This  particular  program  is  set  up  to  plot  a  10  x  10  kilometer  map  segment  at 
a  scale  of  1:25000  yielding  a  map  40  x  40  cm.  (another  version  of  the  program 
yields  a  30  x  10  km.  map  area).  Plot  units  for  the  program  are  meters ,  so 
map  coordinates  to  be  plotted  are  in  the  range  0.  to  10,000.  for  both  X  and 
Y  coordinates.  The  program  currently  has  9  active  options  which  are  selected 
by  the  first  input  data  card:  a  1  In  column  j  selects  option  j  and  a  0  in 
column  j  suppresses  the  option  (j*l,...,9). 

1.  Option  1  Coordinate  Grid.  This  option,  if  selected,  plots  a 
1  x  1  km  grid  over  the  map  area. 

2.  Option  2  Label  Coordinates.  This  option  prints  UTM  coordin¬ 
ates  for  each  kilometer  In  the  map  boundary. 

3.  Option  3  Terrain  Contour  Map.  Option  3  plots  a  contour  map 
of  the  battlefield  area.  Substantial  preprocessing  (see  section  B)  Is  done  to 
prepare  and  place  on  a  disk  file  the  X,  Y  coordinates  defining  each  contour 


2 


1  REPLACE  THIS  CARO  WITH  STANDARD  JOB  CARD  WITH  TIRE  •  5 

2  //  EXEC  FORTCLGU 

3  //FORT. STS1N  OD  « 

II  C  PLOT  PROGRAH  FOR  10  X  10  KH  TERRAIN  BOX. 

S  DIMENSION  10PT(10).BX(7).BT(7).EX(7).ET(7l.X(3600).T(3600l. 

0  1  ITR  (1001,1  TITLE  (20) 

7  DATA  BX/-500., 10500.. 10500.. -500., -500..  0..1./, 


a 

1  BT/-500..-50Q.. 10500.. 10500.  ,-SOO.,  1 

9 

2  EX/O. . 10000. . 10000. .0. .0. .0. , 1 . /. 

10 

3  ET/O. ,0. . 10000. . 10000. . 0. .0. . 1 .  / 

11 

DATA  LNASK1/Z0F0F/ 

12 

C 

13 

C 

INPUT  OPTIONS  AS  1  •  DESIRED,  0  -  NOT  0ES1RE0 

IN 

C 

lOPT(l)  —  COORDINATE  grid 

15 

C 

(2)  —  LABEL  COORDINATES 

16 

C 

(31  —  TERRAIN  CONTOUR  NAP 

17 

C 

(4)  —  ACCENT  CONTOURS  DIVISIBLE  BT  100 

18 

c 

(Si  —  FORESTS  SHADED 

19 

c 

(6)  —  ORAN  LINES  (EG.  ROUTES) 

20 

c 

(71  —  ORAN  STMBOLS  (EG.  POSITIONS) 

21 

c 

(81  —  TITLE 

22 

c 

(9)  --  OUTLINE  ELLIPSES  (EG.  FIELDS) 

23 

c 

2N 

RE  AO  (5.7)  I  OPT 

25 

7 

FORMAT  (1011) 

26 

C 

8ATTLEFIEL0  LONER  LEFT  CORNER  COORDS  IN  METERS 

27 

XL08T-50000. 

28 

YL0BT-93000. 

29 

c 

30 

c 

PLOT  FRAME 

31 

c 

32 

CALL  PLOTS  (0.0,0) 

33 

CALL  NEHPEN  (5) 

3N 

CALL  LINE  (BX.BT. 5. 1,0.0) 

35 

CALL  LINE  (EX, ET.5, 1.0,0) 

38 

CALL  NEHPEN  (11 

37 

c 

38 

c 

PLOT  COORDINATE  GRID 

39 

c 

NO 

IF  (IOPT  (1) . N£.  1)  GO  TO  200 

Ml 

NR1TE  (8.107) 

N2 

107 

FORMAT  (*  OPTION  1  --  COORDINATE  GRID') 

N3 

CALL  GRID (0. ,0. , 10. 1000. . 10, 1000. .LMASK1) 

MM 

C 

MS 

C 

PLOT  COORDINATE  LABEL  NUMBERS 

N6 

c 

N7 

200 

IF  (IOPT  (2J.NE.il  GO  TO  300 

M8 

HAITE  (6,207) 

V9 

207 

FORMAT  ( *  OPTION  2  —  COORDINATE  LABELS') 

SO 

CX«-100. 

Figure  1.  Map  Plot  Program 
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SI 

cr— 315. 

52 

CTT-10185. 

S3 

OX— 445. 

54 

O'XT- 10055. 

55 

OT— 65. 

56 

XB-XLOBY/lOOO. 

57 

YB«YL0BT/1000. 

58 

HT  *  130. 

59 

DO  250  I«l.ll 

60 

CALL  NUHBER (CX.CT.HT. XB.O. 0,- I) 

61 

CALL  NUHBER ICX.CTT.HT, XB.O. 0,-1 1 

62 

CX«CX*1000. 

63 

XB-X8+1 

64 

CALL  NUHBER 10X. OT.HT.TB.0. 0.-1) 

65 

CALL  NUHBER (OXT.DT.HT , TB.0.0,-1) 

66 

DT*DT»1000. 

67 

250 

YB-TB-M 

68 

C 

69 

C  PLOT  TERRAIN  CONTOUR  HAP 

70 

C 

71 

300 

IF  (IOPT  (31.NE.il  GO  TO  500 

72 

NR1TE  (6.3071 

73 

307 

FORHAT  ( *  OPTION  3  --  TERRAIN  CONTOUR  LINES’! 

74 

IF  (IOPT  (41.E0.il  NRITE  (8.407) 

75 

407 

FORMAT C  OPTION  4  —  ACCENT  100  M.  CONTOURS 

76 

310 

REA0  0.317.END-3901  NP.CV 

77 

317 

FORMAT  US. F10.0) 

78 

READ  (3.327)  (X  (1)  .Y  (I) ,  I-l.NP) 

79 

327 

FORMAT  (8F10.2) 

80 

X(NP*!)<0. 

81 

X(NP+2)-l. 

82 

T(NP*1)«0. 

83 

Y(NP»21-1. 

84 

CALL  HEMPEN  (1) 

85 

IF  (IOPT  (4) . NE.  1)  GO  TO  350 

86 

C 

87 

C 

ACCENT  CONTOURS  0IVI31BLE  BY  100. 

88 

C 

89 

ICV-CV/lOO. 

90 

XXCV-CV-1CV«100. 

91 

IF  (ABS  (XXCV)  .  LT .0.1)  CALL  NEMPEN  (4) 

92 

350 

CALL  LINE  (Y.X.NP.  1.0.0) 

93 

GO  TO  310 

94 

C  OUT  OF  DATA 

95 

390 

CALL  NEMPEN  (1) 

96 

C 

97 

C  SHADE  FORESTED  AREAS 

98 

C 

99 

500 

IF  (IOPT  (5)  .NE.  1)  GO  TO  600 

too 

MR1TE  (8.517) 

Figure  1  (Continued). 
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101 

517 

FORMAT C  OPTION  5  —  SHADE  FORESTS') 

102 

HT-75. 

103 

xc-so. 

104 

00  570  I»l,100 

105 

READ  (2,  507)  (ITR  (J)  .  J«1 , 100) 

106 

507 

FORMAT  (SOI  1,30X1 

107 

YC-50. 

108 

DO  540  J- 1,100 

109 

IF  (ITR  (J)  .EQ.O)  GO  TO  520 

110 

CALL  SYMBOL  (XC.TC.HT.  9.0. .-1) 

111 

520 

YC-TC-MOO. 

112 

540 

CONTINUE 

113 

XC-XC-MOQ. 

111 

570 

CONTINUE 

115 

C 

116 

C  PLOT  LINES  (EG.  ROUTES) 

117 

C 

1 18 

600 

IF  (IOPT  (6)  . NE.  1)  GO  TO  700 

119 

MRITE  (6.627) 

120 

627 

FORMAT  ( ’  OPTION  6  —  PLOT  LINES') 

121 

CALL  NEMPEN  (2) 

122 

610 

READ  (5.607)  NP 

123 

607 

FORMAT  (15) 

121 

IF  (NP.E0.999)  GO  TO  690 

125 

MRITE  (6.607)  NP 

126 

READ  (5,617)  (X  (1)  ,T  II)  ,  1»1  ,NP) 

127 

MRITE  (6,617)  (X(1),Y(1),I»1 ,  NP) 

128 

617 

FORMAT  (8F10.0) 

129 

DO  640  I • 1 , NP 

130 

X  (11  -  X  (I)  -XLOBT 

131 

640 

T  (I)  -  T II)  -  YLOBT 

132 

XINP+D-O. 

133 

X  (NP»2)  «1 . 

134 

Y(NP«ll-0. 

135 

T(NP+2)«1. 

136 

CALL  LINE  (X.T.NP,  1,0,0) 

137 

GO  TO  610 

138 

690 

CALL  NEHPEN(l) 

139 

C 

140 

C  PLOT  SYMBOLS  (EG.  POSITIONS) 

141 

C 

142 

700 

IF  (IOPT  (7)  .NE.l)  GO  TO  800 

143 

MRITE  (6.707) 

144 

707 

FORMAT C  OPTION  7  —  PLOT  POSITIONS') 

145 

NT  -  SO. 

146 

710 

RE  AO  (5,717)  XC.YC.ISTH 

147 

717 

FORMAT  (2F10.0.I5) 

148 

IF  (1SYH.E0.999)  GO  TO  800 

149 

XC*XC-XL08T 

150 

TC-TC-TL08T 

Figure  1  (Continued). 
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1STM.0..-I) 


1S1 

CALL  STHBOL  (XC.TC.HT,  ISTM.0..-1) 

1 

152 

GO  TO  710 

1S3 

C 

15V 

C  PLOT  TITLE 

155 

C 

1S6 

800 

IFlIOPT(B).NE.l)  GO  TO  900 

157 

RE  AO  (5.807)  I  TITLE 

158 

807 

FORMAT  (20AV) 

159 

WRITE  (6,817)  IT1TLE 

1 

160 

817 

FORMAT  C  OPTION  8  —  TITLE  \20AV) 

1 6 1 

XC— 700. 

1 

182 

TC— VOO. 

163 

HT-135. 

16V 

CALL  SYMBOL (XC, TC. MT. 1TITLE. 90. 0.80) 

165 

C 

166 

C  OUTLINE  ELLIPSES 

167 

C 

168 

900 

IF  (10PT  (9)  .  NE .  1 )  GO  TO  1000 

169 

WRITE  (8,907) 

170 

907 

FORMAT  1*  OPTION  9  —  PLOT  ELLIPSES’) 

171 

910 

RE AD  (5 . 9 1 7)  NUN , XC . TC . SAHA J, SAM I N . ANGL E 

172 

WRITE  (6.917)  NUH.XC.rC. SAHA J. SAHIN. ANGLE 

173 

917 

FORMAT  (15. 5F 10.2) 

17V 

IF  (NUN  .EO.  999)  GO  TO  1000 

175 

CALL  NEWPEN  (1) 

176 

XC-XC-XL08Y 

177 

YC-TC-YLOBT 

I 

178 

TMOPI-3. 1 V159265-2.0 

179 

ANGLE-ANGLE  «  TWOPI  /  360. 

180 

ASQ-  SAHAJ— 2 

181 

8S0-SAMIN— 2 

182 

C-THOPI  «  SORT  ( (ASQ*BSQ)  /2.0) 

183 

ZN- C/50.0 

18V 

N-ZN-1 

185 

NC— 1 

188 

THETA-0.0 

187 

00  9S0  I-l.N 

188 

ASQ-  (ASO-BSO)  /  (ASO-  (SIN  (THETA)  -m2)  -BSQh  (COS  (THETA)  mm2)  ) 

189 

R-30RT  (ASQ) 

190 

APT-ANGLE  ♦  THETA 

i 

191 

XX-XC+A-COS  (APT! 

192 

TT-TC-A«3lN  (APT) 

193 

CALL  STHBOL  (XX, TT. 25. .1.0., NC) 

I9V 

NC— 2 

195 

THETA-THETA  *  50.0/R 

198 

950 

CONTINUE 

197 

GO  TO  910 

198 

1000 

CONTINUE 

199 

CALL  PLOT  (0..0.. 999) 

200 

STOP 

Figure  1  (Continued). 
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201  END 

202  REPLACE  THIS  CARO  MITH  A  STANOARO  ORANGE  END  OF  FILE  CARD 

203  //GO.PLOTPARH  00  » 

204  tPLOT  XHlN— 999..  XHAX-12000..  THIN— 999.  .YHAX-1 2000.  .UNITS*.  0254, 

205  SCALE*. 00004. STRIP- 14000.  (END 

206  //G0.FT02F001  00  UNIT-2314. V0L-SER-PAT001 , OSN-PLTFLTR. 01 SP-SHR 

207  //G0.FT03F001  00  UNI T-2314. V0L-SER-PAT001 .DSN-PLTFL50. 01SP-SHR 

208  //G0.STS1N  00  •« 

209  1111111110 


210 

3 

21) 

52300. 

96150. 

51620. 

96350.  50950. 

93100 

212 

999 

213 

52350. 

96200. 

14 

214 

52400. 

96200. 

00 

215 

52450. 

96300. 

14 

216 

0.0 

0.0 

999 

217 

TEST  PLOT 

FOR  TECH 

REPORT 

218  1  51500.  95000.  500.  200.  45. 

219  999 

220  REPLACE  THIS  CARO  NITH  A  STANDARD  ORANGE  END  OF  FILE  CARO 


Figure  1  (Continued). 
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line  on  the  map.  This  file,  which  contains  perhaps  50,000  X,  Y  pairs  is  read 
by  the  plot  program  and  plotted.  The  current  file  uses  10  m.  contour  spacing. 

4.  Option  4  .  Accent  Contours.  If  this  option  is  selected  along 
with  option  3,  then  contour  lines  corresponding  to  elevations  evenly  divisible 
by  100  will  be  plotted  darker  than  the  others. 

5.  Option  5.  Shade  Forests.  The  plot  program  reads  from  a  disk 
file  a  100m.  grid  of  0-1  values  over  the  entire  battlefield.  When  a  1  is 
read,  signifying  the  presence  of  forests  in  that  100  x  100  grid,  a  Y  symbol  is 
plotted  on  the  map. 

6.  Option  6.  Draw  Lines.  If  option  6  is  selected,  the  plot 
program  will  read  X,  Y  coordinates  from  cards,  and  connect  them  by  straight 
lines.  This  option  is  useful  for  plotting  routes  for  moving  vehicles  or  firer/ 
target  pairs  for  each  shot.  The  data  should  be  punched  as  follows: 

Card  1  NP  -  number  of  points  to  follow  (Format  15) 

Card  2  X1  Y^  Y^  etc.  for  NP  points  (Format  8F10.0) 

1  continuing  on  successive  cards  as  needed. 

Card  k  NP  -  for  the  next  line  to  be  plotted 

Card  k+1  X,  Y,  X,  Y  coordinates  for  the  line 

Card  n  NP  =  999  signal  to  end  option  6. 

7.  Option  7  Plot  Symbols.  This  option  reads  data  from  cards  and 
plots  the  indicated  symbols  on  the  map.  The  option  is  useful  for  plotting 
snapshots  of  element  positions  during  the  simulated  battle.  One  card  is  read 
for  each  symbol  to  be  plotted.  The  card  contains  three  values:  X,  Y,  (the  X 
and  Y  coordinates  of  the  symbol  location  on  the  map)  and  ISYM  (an  integer  code 
for  the  symbol  to  plot)  read  in  format  (2F10.0,  15).  The  list  of  available 
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symbol  codes  is  given  in  the  VERSATEC  Graphics  Manual,  reference  [1],  page 
B-4.  A  symbol  value  ISYM  =  999  terminates  the  option. 

8.  Option  8  Print  Title.  Option  8  reads  a  single  card  of 
character  data  and  plots  it  on  the  left  hand  boraer  of  the  map. 

9.  Option  9  Plot  Ellipses.  Option  9  reads  from  cards  the  para¬ 
meters  of  ellipses  which  are  then  plotted  overlaying  the  battlefield.  This 
option  is  useful  for  showing  the  location  of  minefields  and  other  areas  on 
the  battlefield.  One  card  is  read  for  each  ellipse  containing  the  following 
values: 


NUM 

-  sequence  number  -  (999  for  end  of  data)  (15) 

XC 

-  X  coordinate  of  ellipse  center 

(F10.2) 

YC 

-  Y  coordinate  of  ellipse  center 

(F10. 2) 

SAMAJ 

-  length  of  semi -major  axis 

(F10. 2) 

SAM  IN 

-  length  of  semi -mi nor  axis 

(FI  0.2) 

ANGLE 

-  angle  in  degrees  measured  counterclockwise  from 

east  to  the  major  axis 

(FI  0.2) 

A  section  from  a  map  plotted  by  this  program  is  included  as  Figure  2. 
All  of  the  options  were  used  in  its  creation.  The  data  input  cards  for  this 
plot  are  shown  in  Figure  1. 

B.  Preprocessor  Programs  and  Disk  Data  Files 

The  data  used  to  plot  the  contour  lines  and  forested  areas  is 
computed  in  advance  and  stored  on  disk  to  speed  execution  of  the  plot  program. 

The  forest  preprocessor  does  a  simple  100m.  scan  of  the  battlefield 
area  and  evaluates  tree  height  at  each  sample  point.  Tree  height  of  zero  is 
stored  as  a  0,  and  does  not  plot  a  symbol  at  that  point.  Positive  tree  height 
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FOR  TECH  REP0R' 


Figure  2.  Sample  Map 
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results  in  a  1  stored  on  disk  and  a  Y  symbol  plotted.  The  tree  data  is  read 
from  FORTRAN  data  set  FT02F001  by  the  plot  program. 

The  contour  map  preprocessor  is  much  more  complex,  and  was  bor¬ 
rowed  from  the  NPS  Computer  Center's  library  contour  mapping  routine  CONTUR. 
The  routine  was  modified  so  that  instead  of  generating  plot  calls  directly  it 
now  writes  X,Y  line  coordinates  to  disk  file  FT03F001  for  future  reading  by 
the  PLOT  program.  The  modified  program  is  available  from  the  author. 
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III.  Code  Reconciliation  Program  -  RECON 

A.  Introduction 

In  a  major  programming  effort  (such  as  the  STAR  model)  where  several 
people  are  independently  developing  program  modules  to  be  added  to  the  model, 
the  problem  of  bringing  together  the  developing  modules  into  a  coirmon  master 
code  is  time  consuming  and  liable  to  oversight  errors.  A  code  reconciliation 
program  named  RECON  has  been  written  to  simplify  this  task.  It  presumes  that 
two  programs  (call  them  A  and  B)  have  evolved  from  some  common  ancestor  code. 

A  and  B  are  thus  mostly  identical,  but  involve  changes  to  some  subroutines  of 
the  model,  the  addition  of  some  new  routines,  and  possibly  also  deletion  of 
some  routines.  The  code  reconciliation  program  reads  the  source  code  for  the 
A  and  B  programs  and  prints  out  information  about  routines  that  match,  lines 
of  code  which  differ,  and  routines  that  are  present  in  one  of  A  or  B  but  absent 
from  the  other. 

The  RECON  program  is  written  in  SIMSCRIPT.  It  is  a  fairly  simple  pro¬ 
gram  as  word-processors  go,  but  is  too  complex  to  describe  in  detail  here. 

The  source  code  is  available  from  the  author.  In  this  report  we  concentrate  on 
the  features,  use,  and  limitations  of  the  RECON  program. 

B.  Inputs 

The  main  Inputs  to  the  RECON  program  are  the  two  programs,  A  and  B, 
to  be  compared.  Program  A  Is  read  from  SIMSCRIPT  Input  unit  1  and  program  B 
Is  read  from  unit  2.  The  user  can  define  these  units  to  point  to  whatever 
physical  devices  are  desired  -  usually  to  disk  data  sets  containing  the  source 
program  card  Images. 

For  example,  the  following  IBM/360  JCL  points  unit  1  to  a  program  A 
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Stored  in  three  source  program  modules  on  a  disk.  The  three  modules  are 
automatically  concatenated  in  the  order  given. 

//GO- SIMUOl  DD  UNIT=231 4 ,V0L=SER=DISK03  ,DISP=SHR  ,DSN=PRCGA1 
//  OD  UNIT=2314  ,VOL=SER=DISKO3,DI$P=SHR,DSM=PP.0GA2 

//  DD  UNIT=2314,V0L=SER=DISK03,DISP=SHR,DSN=PP0GA3 

In  addition,  there  are  3  inputs  which  are  read  from  unit  5  —  usually 
3  cards.  The  first  card  contains  an  integer  input  value  FILE.LGTH  in  free 
format.  It  defines  the  maximum  number  of  card  images  from  each  program  kept 
in  RECON  arrays  at  any  given  time.  If  RECON  finds  a  mismatch  in  a  given 
routine  of  the  A  and  8  programs,  then  it  will  look  up  to  FILE.LGTH  cards  ahead 
in  each  routine  trying  to  reestablish  a  match.  A  reasonable  value  for 
FILE.LGTH  is  50,  larger  values  may  slow  execution  since  up  to  FILE.LGTH**2 
card  comparisons  may  be  made  for  each  failure  to  match. 

The  second  input  card  contains  an  alphabetic  description  of  program  A 
(for  example,  its  name)  which  is  printed  on  the  RECON  output  for  identification 
purposes.  Up  to  80  characters  may  be  used.  The  third  input  card  describes 
program  B  in  an  analogous  fashion. 

C.  Module  Definition  and  Sequencing 

RECON  breaks  each  of  programs  A  and  B  into  a  sequence  of  modules.  A 
module  is  a  segment  of  code  which  starts  with  a  header  card  and  ends  with  .the 
word  END. 

Header  cards  are  cards  on  which  the  first  non-blank  characters  are  the 

keywords :  PREAMBLE 

MAIN 
EVENT 
UPON 
ROUTINE 
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corresponding  to  the  standard  SIMSCRI PT  program  elements.  Each  keyword  must 
be  followed  by  a  blank(if  there  is  room  on  the  card  for  it).  The  EVENT,  UPON, 
and  ROUTINE  header  cards  should  also  contain  a  program  element  name  following 
the  keyword.  RECON  will  store  up  to  19-character  names.  A  name  must  be 
followed  by  a  blank  column  or  by  a  left  parenthesis  if  there  is  room  for  it 
on  the  card.  The  SIMSCRIPT  keywords  TO  and  FOR  may  appear  between  the  header 
keyword  and  the  name.  Since  RECON  ignores  TO  and  FOR  in  this  context,  these 
two  words  may  not  be  used  as  module  names. 

The  end  of  a  module  is  signalled  by  any  card  that  has  the  characters 
END  separate  from  other  characters(that  is,  immediately  preceeded  and  followed 
by  blanks  if  there  is  room  on  the  card)  before  any  11  comment  indicators.  END 
need  not  be  the  first  word  on  the  card. 

RECON  operates  on  one  module  at  a  time  (in  each  of  A  and  B).  If  the 
current  module  headers  match  (i.e.  both  PREAMBLE,  both  MAIN,  both  ROUTINE  with 
matching  name,  or  both  EVENT  or  UPON  with  matching  name)  then  RECON  will  go 
inside  the  module  and  compare  its  contents  line  by  line.  (See  section  D.). 

If  the  current  module  headers  do  not  match,  then  RECON  will  print  one  of  the 
modules  as,  for  example, 

"MODULE  IN  FILE  A  -  NOT  IN  FILE  B", 

and  advance  to  the  next  module  header  in  that  file  to  attempt  a  match  again. 

In  order  to  determine  which  program  file  to  advance  If  a  match  does 
not  occur,  RECON  assumes  that  both  programs  contain  modules  In  the  following 
standardized  order.  First  comes  the  PREAMBLE,  followed  by  the  MAIN  program, 
and  then  all  other  EVENT,  UPON,  and  ROUTINE  modules  arranged  so  that  their  names 
are  in  alphabetic  order. 
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CAUTION:  Alphabetic  order  is  defined  by  the  IBM  SIMSCRIPT  collating 


sequence  which  is 

ABC  -  XYZ012  89  space  dot 

Note  that  the  space  (blank)  cones  after  the  alphanumeric  characters  but  before 

the  dot  (period).  This  results  in  a  slightly  nonstandard  alphabetization  in 

which  the  following  is  a  proper  sequence  of  program  element  names: 

RESET 

RES2 

RES 

RES. MOVE 

RECON  uses  the  alphabetic  order  of  names  only  when  deciding  which  file  to 
advance  if  headers  do  not  match.  If  both  A  and  B  have  the  same  module  headers 
and  names  in  the  same  sequence,  then  the  alphabetic  ordering  will  never  be 
considered.  But  if  A  has  modules  named  (in  sequence)  J,  K,  L,  M,  N  while 
those  of  B  are  J,  N,  K,  L,  M,  then  RECON  will 
compare  J's 

declare  module  K  in  file  A  -  not  B 

declare  module  L  in  file  A  -  not  B 

declare  module  M  in  file  A  -  not  B 

compare  N's 

declare  module  K  in  file  B  -  not  A 

declare  module  L  In  file  B  -  not  A 

declare  module  M  In  file  B  -  not  A 

with  the  result  being  that  many  of  the  modules  are  not  compared. 

D.  Comparisons  Inside  a  Module 

When  RECON  has  located  a  pair  of  matching  headers,  it  proceeds  to  do 
line  by  line  comparisons  of  program  A  to  program  B  within  the  module.  It 
should  be  noted  that  only  the  header  keyword  and  the  name  are  used  in  matching 
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header  cards.  Other  information  such  as  given  and  yielding  arguments  may  be 
different  on  the  header  cards. 

Lines  from  A  and  B  including  the  headers  are  then  compared  character 
by  character.  If  all  80  characters  match,  the  lines  are  not  printed,  but  a 
message  is  printed  indicating  the  match: 

"Matching  block  of  5  lines,  A  lines  16  to  20.  B  lines  17  to  21" 

If  the  entire  modules  match,  there  will  be  only  one  such  message  for  each  module. 

If  any  character  of  the  current  line  in  A  fails  to  match  the  corres¬ 
ponding  character  of  the  current  line  in  B,  then  the  lines  do  not  match.  In 
this  case  RECON  looks  ahead  in  both  files  trying  to  find  the  closest  place 
where  a  match  can  be  reestablished.  Up  to  FILE.LGTH  future  lines  are  consid¬ 
ered  in  each  of  A  and  B  (but  never  beyond  the  END  of  the  current  module). 

Messages  identifying  the  non-matching  portions  are  printed  such  as: 

BLOCK  IN  FILE  A  —  NOT  IN  FILE  B 

2  LINES,  FROM  LINE  24  TO  LINE  25 

24  LET  X  =»  1 

25  CALL  TOTAL 

All  non-matching  lines  are  printed  for  easy  cross  reference  to  programs  A  and  B. 

If  a  match  cannot  be  reestablished  by  the  end  of  the  modules  or  within 
FILE.LGTH  lines,  then  the  module  is  abandonned  -  remaining  lines  are  not  com¬ 
pared,  and  both  programs  are  advanced  to  the  next  module. 

Any  program  lines  which  do  not  lie  between  header  and  end  cards  are 
Identified  as  being  orphans  and  are  printed. 
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IV.  Code  Plot  Program 


As  an  aid  for  documentation  of  computer  programs,  a  code  plotting 
program  has  been  written.  Computer  listings  of  computer  programs  are  often 
too  faint  to  reproduce  well  in  program  documentation  and  may  require  photo¬ 
reduction  to  conveniently  fit  technical  report  or  thesis  page  sizes.  The 
code  plotting  program  uses  the  VERSATEC  plotter  to  produce  crisp  easily  re¬ 
produced  page  size  copies  of  card  decks.  Line  numbers  may  also  be  added. 

This  program  is  written  in  FORTRAN  and  calls  standard  VERSATEC  graphics  sub¬ 
routines  A  program  listing  (plotted  by  the  program  itself)  appears  in 

Figure  3  and  includes  JCL  and  sample  data  cards. 

The  code  plot  program  assumes  the  following  input:  the  information 
to  be  plotted  is  read  from  cards  —  one  card  per  plot  line.  All  80  card  col¬ 
umns  are  plotted.  The  input  deck  of  cards  to  be  plotted  is  arranged  into 
modules  each  of  which  starts  a  new  plot  page.  Each  module  starts  with  a  line 
number  card  (which  is  not  plotted)  and  ends  with  a  nines  card  (which  is  also 
not  plotted.) 

The  line  number  card  contains  a  single  input  integer  N  in  15  format. 

IfN  >.  0,11ne  numbers  will  be  plotted  at  the  left  of  each  line  of  information. 
The  first  line  number  is  N  and  successive  line  numbers  Increase  by  one  for  each 
line.  If  N  *  -1,  the  line  number  sequence  continues  uninterrupted  from  the 
previous  module.  If  N  8  -2,  no  line  numbers  will  be  plotted. 

The  nines  card  signals  the  end  of  a  module  and  terminates  plotting  for 
the  current  page.  It  contains  9's  In  the  first  eight  column  positions.  (Thus 
It  Is  impossible  to  plot  a  card  which  starts  with  8  nines.) 

Up  to  50  lines  are  plotted  on  each  page.  Modules  which  are  longer 
than  50  lines  automatically  continue  on  additional  pages  with  the  line  number 
sequence  unbroken  until  a  nines  card  Is  encountered. 
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1  STANDARD  JOB  CARO  WITH  TIHE-1  GOES  HERE 

2  //  EXEC  FORTCLGH 

3  //FORT. STS IN  DO  « 

V  C  PLOT  PROGAAH  FOR  80  CHAR  CARO  IMAGES  IN  TECH  REPORT  FORMAT 

5  DIMENSION  XBOX  (71,  TBOX  (7) .  ITEXT  (20) 

6  DATA  XBOX/O.O.O.O.B.S.a.S.O.O.O.O.I.O/. 

7  -  TBOX/O. 0. 11. 0,:i. 0,0. 0.0. 0.0. 0.1.0/.  ICHK/'9S99'/ 

8  CALL  PLOTS  (0,0.0) 

9  XST  «  0.0 

10  ZLlNE  •  1.0 

11  C  MAIN  LOOP  START  NEN  CODE  SEGMENT 

12  C  GET  LINE  NUMBER  CODE 

13  SO  READ  (5.I27.EN0-300)  N 

14  127  FORMAT  (IS) 

15  IF  (N.GE.O)  ZLlNE  •  N 

ie  c  hove  over  for  neh  page 

17  100  XST  -  XST  ♦  9.0 

IB  DO  120  1  >  l.S 

19  120  XBOX  (1)  •  XBOX(l)  ♦  9.0 

20  C\ OUTLINE  THE  PAGE 

21  CALL  NEHPEN  (1) 

22  CALL  LINE  (XBOX. TBOX. S. 1,0.0) 

23  C  PRINT  THE  PAGE 

24  CALL  NENPEN  (2) 

25  X  -  XST  *  2.0 

28  XX  -  XST  ♦  1.5 

27  T  -  9.5 

28  DO  200  I  -  1.50 

29  READ (5, 157,EN0»300)  ITEXT 

30  157  FORMAT  (20A4J 

31  IF  ( (ITEXT  (1)  .EQ.  ICMK)  .  ANO.  (ITEXT  (2)  .EQ.  ICHK) )  GO  TO  50 

32  T  -  T  -  0.15 

33  CALL  SYMBOL (X,T. 0.070, ITEXT. 0.0, 80) 

34  IF  (N  .EO.  -21  GO  TO  200 

35  CALL  NUMBER  (XX. T. 0.07, ZLlNE. 0. 0,-1) 

38  ZLlNE  -  ZLlNE  ♦  1 

37  200  CONTINUE 

38  GO  TO  100 

39  300  CALL  PLOT  (0..0..999) 

40  STOP 

41  ENO 

42  REPLACE  THIS  CARO  M1TH  A  STANDARD  ORANGE  END  OF  FILE  CARO 

43  //GO.PLOTPAAM  DO  « 

44  (PLOT  XMIN-6. 0.XMAX-150.0. THIN— 3.0, TMAX-12.0  «ENO 

45  //G0.3TS1N  00  DATA 

48  LINE  NUMBER  CARO  GOES  HERE 

47  INPUT  OECK  TO  BE  PLOTTED  GOES  HERE 

48  NINES  CARO  GOES  HERE 

49  REPLACE  THIS  CARO  NITH  A  STANOAAD  ORANGE  ENO  OF  FILE  CARO 


Figure  3.  Code  Plot  Program 
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The  last  module  in  the  input  deck  is  ended  with  a  nines  card  and 
followed  by  the  standard  orange  end  of  file  card  (/*). 
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